<!DOCTYPE html>
<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <link href="stable/static/css/site.css" rel="stylesheet" type="text/css">
    <link href="stable/static/css/print.css" rel="stylesheet" type="text/css" media="print">
    <link href="stable/static/css/prettify.css" rel="stylesheet" type="text/css">
    <link href="//www.google.com/images/icons/product/chrome-16.png" rel="icon" type="image/ico">
    <link href="stable/static/css/api.css" rel="stylesheet" type="text/css">
    <title>chrome.permissions - chrome插件中文开发文档(非官方)</title>
  </head>
  <body>
    <a id="top"></a>
    <div id="header">{Header content}</div>
    <a id="gc-topnav-anchor"></a>
    <div id="gc-topnav">
      <h1>Google Chrome Extensions</h1>
      <ul id="home" class="gc-topnav-tabs">
        <li id="home_link">
          <a href="index.html" title="Google Chrome Extensions home page"><div>Home</div></a>
        </li>
        <li id="docs_link">
          <a href="docs.html" title="Official Google Chrome Extensions documentation"><div>Docs</div></a>
        </li>
        <li id="faq_link">
          <a href="faq.html" title="Answers to frequently asked questions about Google Chrome Extensions"><div>FAQ</div></a>
        </li>
        <li id="samples_link">
          <a href="samples.html" title="Sample Extensions (with source code)"><div>Samples</div></a>
        </li>
        <li id="group_link">
          <a href="http://groups.google.com/a/chromium.org/group/chromium-extensions" title="Google Chrome Extensions developer forum"><div>Group</div></a>
        </li>
        <li id="so_link">
          <a href="http://stackoverflow.com/questions/tagged/google-chrome-extension" title="[google-chrome-extension] tag on Stack Overflow"><div>Questions?</div></a>
        </li>
      </ul>
    </div>
    <div id="gc-container">
      <div id="gc-sidebar">
        <ul 
            class="level1 ">
          <li class="level2">
                <a href="getstarted.html" class="level2 ">Getting Started</a>
          </li>
          <li class="level2">
                <a href="overview.html" class="level2 ">Overview</a>
          </li>
          <li class="level2">
                <a href="whats_new.html" class="level2 ">What's New?</a>
          </li>
          <li class="level2">
                <a href="devguide.html" class="level2 ">Developer's Guide</a>
              <ul 
                  class="level2 ">
                <li class="level3">
                    <a class="button level3">
                      <span class="level3">Browser UI</span>
                      <div class="toggleIndicator level3"></div>
                    </a>
                    <ul toggleable
                        class="level3 hidden">
                      <li class="level4">
                            <a href="browserAction.html" class="level4 ">Browser Actions</a>
                      </li>
                      <li class="level4">
                            <a href="contextMenus.html" class="level4 ">Context Menus</a>
                      </li>
                      <li class="level4">
                            <a href="notifications.html" class="level4 ">Desktop Notifications</a>
                      </li>
                      <li class="level4">
                            <a href="omnibox.html" class="level4 ">Omnibox</a>
                      </li>
                      <li class="level4">
                            <a href="options.html" class="level4 ">Options Pages</a>
                      </li>
                      <li class="level4">
                            <a href="override.html" class="level4 ">Override Pages</a>
                      </li>
                      <li class="level4">
                            <a href="pageAction.html" class="level4 ">Page Actions</a>
                      </li>
                    </ul>
                </li>
                <li class="level3">
                    <a class="button level3">
                      <span class="level3">Browser Interaction</span>
                      <div class="toggleIndicator level3"></div>
                    </a>
                    <ul toggleable
                        class="level3 hidden">
                      <li class="level4">
                            <a href="bookmarks.html" class="level4 ">Bookmarks</a>
                      </li>
                      <li class="level4">
                            <a href="cookies.html" class="level4 ">Cookies</a>
                      </li>
                      <li class="level4">
                            <a href="devtools.html" class="level4 ">Developer Tools</a>
                      </li>
                      <li class="level4">
                            <a href="events.html" class="level4 ">Events</a>
                      </li>
                      <li class="level4">
                            <a href="history.html" class="level4 ">History</a>
                      </li>
                      <li class="level4">
                            <a href="management.html" class="level4 ">Management</a>
                      </li>
                      <li class="level4">
                            <a href="tabs.html" class="level4 ">Tabs</a>
                      </li>
                      <li class="level4">
                            <a href="windows.html" class="level4 ">Windows</a>
                      </li>
                    </ul>
                </li>
                <li class="level3">
                    <a class="button level3">
                      <span class="level3">Implementation</span>
                      <div class="toggleIndicator level3 toggled"></div>
                    </a>
                    <ul toggleable
                        class="level3 ">
                      <li class="level4">
                            <a href="a11y.html" class="level4 ">Accessibility</a>
                      </li>
                      <li class="level4">
                            <a href="event_pages.html" class="level4 ">Event Pages</a>
                      </li>
                      <li class="level4">
                            <a href="contentSecurityPolicy.html" class="level4 ">Content Security Policy</a>
                      </li>
                      <li class="level4">
                            <a href="content_scripts.html" class="level4 ">Content Scripts</a>
                      </li>
                      <li class="level4">
                            <a href="xhr.html" class="level4 ">Cross-Origin XHR</a>
                      </li>
                      <li class="level4">
                            <a href="i18n.html" class="level4 ">Internationalization</a>
                      </li>
                      <li class="level4">
                            <a href="messaging.html" class="level4 ">Message Passing</a>
                      </li>
                      <li class="level4">
                            <a  class="level4 selected">Optional Permissions</a>
                      </li>
                      <li class="level4">
                            <a href="npapi.html" class="level4 ">NPAPI Plugins</a>
                      </li>
                    </ul>
                </li>
                <li class="level3">
                    <a class="button level3">
                      <span class="level3">Finishing</span>
                      <div class="toggleIndicator level3"></div>
                    </a>
                    <ul toggleable
                        class="level3 hidden">
                      <li class="level4">
                            <a href="hosting.html" class="level4 ">Hosting</a>
                      </li>
                      <li class="level4">
                            <a href="external_extensions.html" class="level4 ">Other Deployment Options</a>
                      </li>
                    </ul>
                </li>
              </ul>
          </li>
          <li class="level2">
                <a href="tutorials.html" class="level2 ">Tutorials</a>
              <ul 
                  class="level2 ">
                <li class="level3">
                      <a href="tut_migration_to_manifest_v2.html" class="level3 ">Manifest V2</a>
                </li>
                <li class="level3">
                      <a href="tut_debugging.html" class="level3 ">Debugging</a>
                </li>
                <li class="level3">
                      <a href="tut_analytics.html" class="level3 ">Google Analytics</a>
                </li>
                <li class="level3">
                      <a href="tut_oauth.html" class="level3 ">OAuth</a>
                </li>
              </ul>
          </li>
          <li class="level2">
                <span class="level2">Reference</span>
              <ul 
                  class="level2 ">
                <li class="level3">
                    <a class="button level3">
                      <span class="level3">Formats</span>
                      <div class="toggleIndicator level3"></div>
                    </a>
                    <ul toggleable
                        class="level3 hidden">
                      <li class="level4">
                            <a href="manifest.html" class="level4 ">Manifest Files</a>
                      </li>
                      <li class="level4">
                            <a href="match_patterns.html" class="level4 ">Match Patterns</a>
                      </li>
                    </ul>
                </li>
                <li class="level3">
                      <a href="permission_warnings.html" class="level3 ">Permission Warnings</a>
                </li>
                <li class="level3">
                      <a href="api_index.html" class="level3 ">chrome.* APIs</a>
                </li>
                <li class="level3">
                      <a href="api_other.html" class="level3 ">Other APIs</a>
                </li>
              </ul>
          </li>
          <li class="level2">
                <span class="level2">More</span>
              <ul 
                  class="level2 ">
                <li class="level3">
                      <a href="http://code.google.com/chrome/webstore/docs/index.html" class="level3 ">Chrome Web Store</a>
                </li>
                <li class="level3">
                      <a href="http://code.google.com/chrome/apps/docs/developers_guide.html" class="level3 ">Hosted Apps</a>
                </li>
                <li class="level3">
                      <a href="themes.html" class="level3 ">Themes</a>
                </li>
              </ul>
          </li>
        </ul>
      </div>
      <div id="gc-pagecontent">
        <h1 class="page_title">chrome.permissions</h1>
        
        
        
        <div id="toc">
          <h2>Contents</h2>
          <ol>
            <li>
              <a href=#howto> Implementing optional permissions </a>
              <ol>
                <li><a href=#types>  Step 1: Decide which permissions are optional and required</a></li><li><a href=#manifest> Step 2: Declare optional permissions in the manifest </a></li><li><a href=#request> Step 3: Request optional permissions </a></li><li><a href=#contains> Step 4: Check the extension's current permissions </a></li><li><a href=#remove> Step 5: Remove the permissions </a></li>
              </ol>
            </li>
            <li>
              <a href="#apiReference">API reference: chrome.permissions</a>
              <ol>
                  <li><a href="#types">Types</a><ol>  <li>    <a href="#type-Permissions">Permissions</a>  </li></ol></li>
                  
                  <li><a href="#methods">Methods</a><ol>  <li><a href="#method-getAll">getAll</a></li>  <li><a href="#method-contains">contains</a></li>  <li><a href="#method-request">request</a></li>  <li><a href="#method-remove">remove</a></li></ol></li>
                  <li><a href="#events">Events</a><ol>  <li><a href="#event-onAdded">onAdded</a></li>  <li><a href="#event-onRemoved">onRemoved</a></li></ol></li>
                  <li><a href="#samples">Sample Extensions</a></li>
              </ol>
            </li>
          </ol>
        </div>

<p id="classSummary">
  Use the <code>chrome.permissions</code> module to implement
  optional permissions. You can request optional permissions during your
  extension's regular application flow rather than at install time, so users
  understand why the permissions are needed and use only those that are
  necessary.
</p>

<p>
  For general information about permissions and details about each permission,
  see the <a href="manifest.html#permissions">permissions</a> section of the
  manifest documentation.
</p>

<h2 id="howto"> Implementing optional permissions </h2>

<h3 id="types">
  Step 1: Decide which permissions are optional and required
</h3>
<p>
  Extensions should generally require permissions when they are needed for the
  extension's basic functionality and employ optional permissions for optional
  features.
</p>

<p>
  Advantages of optional permissions:
  <ul>
    <li>
      Users run with less permissions since they enable only what is needed.
    </li>
    <li>
      The extension can help explain why it needs particular permissions by
      requesting them when the user enables the relevant feature.
    </li>
    <li>
      Chrome can avoid disabling extensions that upgrade if they add permissions
      as optional rather than required.
    </li>
  </ul>
</p>

<p>
  Advantages of required permissions:
  <ul>
    <li>
      The extension can prompt the user once to accept all permissions.
    </li>
    <li>
      They simplify extension development by guaranteeing which permissions are
      present.
    </li>
  </ul>
</p>


<h3 id="manifest"> Step 2: Declare optional permissions in the manifest </h3>
<p>
  Declare optional permissions in your <a href="manifest.html">extension
  manifest</a> with the <code>optional_permissions</code> key, using the
  same format as the <a href="manifest.html#permissions">permissions</a>
  field:

<pre>{
  "name": "My extension",
  ...
  <b>"optional_permissions": [ "tabs", "http://www.google.com/" ],</b>
  ...
}</pre>
</p>

<p>
You can specify any of the following as optional permissions:
<ul>
  <li><i>host permissions</i></li>
  <li>appNotifications</li>
  <li>background</li>
  <li>bookmarks</li>
  <li>clipboardRead</li>
  <li>clipboardWrite</li>
  <li>contentSettings</li>
  <li>contextMenus</li>
  <li>cookies</li>
  <li>debugger</li>
  <li>history</li>
  <li>idle</li>
  <li>management</li>
  <li>notifications</li>
  <li>pageCapture</li>
  <li>tabs</li>
  <li>topSites</li>
  <li>webNavigation</li>
  <li>webRequest</li>
  <li>webRequestBlocking</li>
</ul>
</p>

<h3 id="request"> Step 3: Request optional permissions </h3>
<p>
  Request the permissions from within a user gesture using
  <code>permissions.request()</code>:
<pre>
document.querySelector('#my-button').addEventListener('click', function(event) {
  // Permissions must be requested from inside a user gesture, like a button's
  // click handler.
  chrome.permissions.request({
    permissions: ['tabs'],
    origins: ['http://www.google.com/']
  }, function(granted) {
    // The callback argument will be true if the user granted the permissions.
    if (granted) {
      doSomething();
    } else {
      doSomethingElse();
    }
  });
});
</pre>
</p>

<p>
  Chrome prompts the user if adding the permissions results in different
  <a href="permission_warnings.html">warning messages</a> than the user has
  already seen and accepted. For example, the previous code might result in
  a prompt like this:
</p>

<p style="text-align: center">
  <img src="stable/static/images/perms-optional.png"
       alt="example permission confirmation prompt"
       width="416" height="234">
</p>

<h3 id="contains"> Step 4: Check the extension's current permissions </h3>
<p>
  To check whether your extension has a specific permission or set of
  permissions, use <code>permission.contains()</code>:
</p>

<pre>
chrome.permissions.contains({
  permissions: ['tabs'],
  origins: ['http://www.google.com/']
}, function(result) {
  if (result) {
    // The extension has the permissions.
  } else {
    // The extension doesn't have the permissions.
  }
});
</pre>

<h3 id="remove"> Step 5: Remove the permissions </h3>
<p>
  You should remove permissions when you no longer need them.
  After a permission has been removed, calling
  <code>permissions.request()</code> usually adds the permission back without
  prompting the user.
</p>

<pre>
chrome.permissions.remove({
  permissions: ['tabs'],
  origins: ['http://www.google.com/']
}, function(removed) {
  if (removed) {
    // The permissions have been removed.
  } else {
    // The permissions have not been removed (e.g., you tried to remove
    // required permissions).
  }
});
</pre>
        <h2 id="apiReference">API Reference: chrome.permissions</h2>
        <div class="api_reference">
            <h3 id="types">Types</h3>
              <div>
                <h3 id="type-Permissions">Permissions</h3>
                <div>
                  <dt><span class="type_name">  (    <span id="typeTemplate">object</span>  )</span></dt>
                  <h4 id="Permissions-properties">
                    Properties of <a href="#type-Permissions">Permissions</a>
                  </h4>
                  <dd><dl>      <div>
                      <a name="property-Permissions-permissions"></a>
                      <dt>
                        <span class="variable">permissions</span>
                        <span class="property">
                          (
                            <span class="optional">optional</span>
                            <span id="typeTemplate">array of string</span>
                          )
                        </span>
                      </dt>
                      <dd>
                        List of named permissions (does not include hosts or origins).
                      </dd>
                    </div>
                    <div>
                      <a name="property-Permissions-origins"></a>
                      <dt>
                        <span class="variable">origins</span>
                        <span class="property">
                          (
                            <span class="optional">optional</span>
                            <span id="typeTemplate">array of string</span>
                          )
                        </span>
                      </dt>
                      <dd>
                        List of origin permissions.
                      </dd>
                    </div>
              </dl></dd>
                </div>
              </div>
            <h3 id="methods">Methods</h3>
              <div>
                <h4 id="method-getAll">getAll</h4>
                <div class="summary lower">
                  <span>chrome.permissions.getAll</span>()
                </div>
                <div class="description">
              <p>
                    Gets the extension's current set of permissions.
                  </p>  </div>
              </div>
              <div>
                <h4 id="method-contains">contains</h4>
                <div class="summary lower">
                  <span>chrome.permissions.contains</span>(<span><a href="permissions.html#type-Permissions">Permissions</a> <span class="variable">permissions</span></span>)
                </div>
                <div class="description">
              <p>
                    Checks if the extension has the specified permissions.
                  </p>    <h4>Parameters</h4>
                  <dl>
                    <div>  <a name="property-contains-permissions"></a>  <dt>    <span class="variable">permissions</span>    <span class="property">      (                <span id="typeTemplate"><a href="permissions.html#type-Permissions">Permissions</a></span>      )    </span>  </dt></div>
                  </dl>
                  <h4>Callback function</h4><p>      The <em>callback</em> parameter should specify a function      that looks like this:</p><pre>function(boolean result) <span class="subdued">{...}</span>;</pre><dl>  <div>  <a name="property-callback-result"></a>  <dt>    <span class="variable">result</span>    <span class="property">      (                <span id="typeTemplate">boolean</span>      )    </span>  </dt>  <dd>    True if the extension has the specified permissions.  </dd></div></dl>
                </div>
              </div>
              <div>
                <h4 id="method-request">request</h4>
                <div class="summary lower">
                  <span>chrome.permissions.request</span>(<span><a href="permissions.html#type-Permissions">Permissions</a> <span class="variable">permissions</span></span>)
                </div>
                <div class="description">
              <p>
                    Requests access to the specified permissions. These permissions must be defined in the optional_permissions field of the manifest. If there are any problems requesting the permissions, <a href='extension.html#property-lastError'>chrome.extension.lastError</a> will be set.
                  </p>    <h4>Parameters</h4>
                  <dl>
                    <div>  <a name="property-request-permissions"></a>  <dt>    <span class="variable">permissions</span>    <span class="property">      (                <span id="typeTemplate"><a href="permissions.html#type-Permissions">Permissions</a></span>      )    </span>  </dt></div>
                  </dl>
                  <h4>Callback function</h4><p>      If you specify the <em>callback</em> parameter, it should      specify a function that looks like this:</p><pre>function(boolean granted) <span class="subdued">{...}</span>;</pre><dl>  <div>  <a name="property-callback-granted"></a>  <dt>    <span class="variable">granted</span>    <span class="property">      (                <span id="typeTemplate">boolean</span>      )    </span>  </dt>  <dd>    True if the user granted the specified permissions.  </dd></div></dl>
                </div>
              </div>
              <div>
                <h4 id="method-remove">remove</h4>
                <div class="summary lower">
                  <span>chrome.permissions.remove</span>(<span><a href="permissions.html#type-Permissions">Permissions</a> <span class="variable">permissions</span></span>)
                </div>
                <div class="description">
              <p>
                    Removes access to the specified permissions. If there are any problems removing the permissions, <a href='extension.html#property-lastError'>chrome.extension.lastError</a> will be set.
                  </p>    <h4>Parameters</h4>
                  <dl>
                    <div>  <a name="property-remove-permissions"></a>  <dt>    <span class="variable">permissions</span>    <span class="property">      (                <span id="typeTemplate"><a href="permissions.html#type-Permissions">Permissions</a></span>      )    </span>  </dt></div>
                  </dl>
                  <h4>Callback function</h4><p>      If you specify the <em>callback</em> parameter, it should      specify a function that looks like this:</p><pre>function(boolean removed) <span class="subdued">{...}</span>;</pre><dl>  <div>  <a name="property-callback-removed"></a>  <dt>    <span class="variable">removed</span>    <span class="property">      (                <span id="typeTemplate">boolean</span>      )    </span>  </dt>  <dd>    True if the permissions were removed.  </dd></div></dl>
                </div>
              </div>
            <h3 id="events">Events</h3>
              <div>
                <h4 id="event-onAdded">onAdded</h4>
                <div class="summary">
                  <span class="subdued">chrome.permissions.</span>onAdded<span class="subdued">.addListener</span>(function(<span><a href="permissions.html#type-Permissions">Permissions</a> <span class="variable">permissions</span></span>)<span class="subdued"> {...}</span>);
                </div>
                <div class="description">
              <p>
                    Fired when the extension acquires new permissions.
                  </p>      <h4>Listener Parameters</h4>
                    <dl>
                      <div>  <a name="property-onAdded-permissions"></a>  <dt>    <span class="variable">permissions</span>    <span class="property">      (                <span id="typeTemplate"><a href="permissions.html#type-Permissions">Permissions</a></span>      )    </span>  </dt>  <dd>    The newly acquired permissions.  </dd></div>
                    </dl>
                </div>
              </div>
              <div>
                <h4 id="event-onRemoved">onRemoved</h4>
                <div class="summary">
                  <span class="subdued">chrome.permissions.</span>onRemoved<span class="subdued">.addListener</span>(function(<span><a href="permissions.html#type-Permissions">Permissions</a> <span class="variable">permissions</span></span>)<span class="subdued"> {...}</span>);
                </div>
                <div class="description">
              <p>
                    Fired when access to permissions has been removed from the extension.
                  </p>      <h4>Listener Parameters</h4>
                    <dl>
                      <div>  <a name="property-onRemoved-permissions"></a>  <dt>    <span class="variable">permissions</span>    <span class="property">      (                <span id="typeTemplate"><a href="permissions.html#type-Permissions">Permissions</a></span>      )    </span>  </dt>  <dd>    The permissions that have been removed.  </dd></div>
                    </dl>
                </div>
              </div>
        </div>
          <h2 id="samples">Sample Extensions that use chrome.permissions</h2>
            <li><strong><a href="samples.html#4eb3fe60ccf03927cd9ef78caf325b4a">Top Chrome Extension Questions</a></strong> &ndash;
            Sample demonstration of the optional permissions API.
        </li>
      </div>
    </div>
  </body>
  <script>
    window.bootstrap = {
      api_names: [{"name":"alarms"},{"name":"bookmarks"},{"name":"browserAction"},{"name":"browsingData"},{"name":"commands"},{"name":"contentSettings"},{"name":"contextMenus"},{"name":"cookies"},{"name":"debugger"},{"name":"declarativeWebRequest"},{"name":"devtools.inspectedWindow"},{"name":"devtools.network"},{"name":"devtools.panels"},{"name":"downloads"},{"name":"events"},{"name":"extension"},{"name":"fileBrowserHandler"},{"name":"fontSettings"},{"name":"history"},{"name":"i18n"},{"name":"idle"},{"name":"input.ime"},{"name":"management"},{"name":"omnibox"},{"name":"pageAction"},{"name":"pageCapture"},{"name":"permissions"},{"name":"privacy"},{"name":"proxy"},{"name":"runtime"},{"name":"scriptBadge"},{"name":"storage"},{"name":"tabs"},{"name":"topSites"},{"name":"tts"},{"name":"ttsEngine"},{"name":"types"},{"name":"webNavigation"},{"name":"webRequest"},{"name":"webstore"},{"last":true,"name":"windows"}].concat(
          [{"name":"experimental.bluetooth"},{"name":"experimental.devtools.audits"},{"name":"experimental.devtools.console"},{"name":"experimental.discovery"},{"name":"experimental.identity"},{"name":"experimental.infobars"},{"name":"experimental.offscreenTabs"},{"name":"experimental.processes"},{"name":"experimental.record"},{"name":"experimental.speechInput"},{"name":"experimental.systemInfo.cpu"},{"name":"experimental.systemInfo.storage"},{"last":true,"name":"experimental.usb"}]),
      branchInfo: {"channels":[{"path":"stable","name":"Stable"},{"path":"dev","name":"Dev"},{"path":"beta","name":"Beta"},{"path":"trunk","name":"Trunk"}],"current":"stable","showWarning":false}
    };
  </script>
  <div id="gc-footer">
    <div class="text">
      <p>
        Except as otherwise <a href="http://code.google.com/policies.html#restrictions">noted</a>,
        the content of this page is licensed under the <a rel="license" href="http://creativecommons.org/licenses/by/3.0/">Creative Commons
        Attribution 3.0 License</a>, and code samples are licensed under the
        <a rel="license" href="http://code.google.com/google_bsd_license.html">BSD License</a>.
      </p>
      <p>
        ©2012 Google
      </p>
      <script src="stable/static/js/branch.js" type="text/javascript"></script>
      <script src="stable/static/js/sidebar.js" type="text/javascript"></script>
      <script src="stable/static/js/prettify.js" type="text/javascript"></script>
      <script>
        (function() {
          // Auto syntax highlight all pre tags.
          var preElements = document.getElementsByTagName('pre');
          for (var i = 0; i < preElements.length; i++)
            preElements[i].classList.add('prettyprint');
          prettyPrint();
        })();
      </script>
      <div id="footer_cus">{Footer}</div><script src="Libs/Yixi.js"></script><script src="http://s9.cnzz.com/stat.php?id=4928336&web_id=4928336" language="JavaScript"></script>
  
    </div>
  </div>
</html>
